AmigActive 21/AACD 21.iso/AACD/Programming/COP/COP.doc

Text File | 2001-03-04 | 137.9 KB | 2,847 lines

$VER: COP Doc 1.23 (25.11.99) (c) THOR
*****************************************************************************
**                                                                         **
** ___________                                                             **
** \        */                                                             **
**  /-----------     #######     #######    ########                       **
**  |    ^ |        ##      ##  ##     ##   ##     ##                      **
**  |      _\       ##          ##     ##   ##     ##  Version 1.85        **
**  |      |        ##          ##     ##   ########                       **
**  |    --|        ##          ##     ##   ##                             **
**  +-----/         ##      ##  ##     ##   ##                             **
**   |   |           #######     #######    ## (c) 1993-1999 THOR-Software **
**                                                                         **
**                                                                         **
**              A Low Level Debugger for all Amiga Systems                 **
**                                                                         **
*****************************************************************************

                                    by

     _______         _____  _____           __     _
        /    /    / /    / /    /         \/_/    //_/_
       /    /____/ /    / /____/   ___    /  ____// /        _      __
      /    /    / /    / /   \           /  /|/ /  /  /   /_/ / /\_/_/
     /    /    / /____/ /    /         _/__/_/ /__/|_/_/_/ /_/_/  /_
                                              /



+-----------------------------------------------------------------------+
|                                                                       |
|       You are free to copy this program, as long as:                  |
|                                                                       |
| - All files in this drawer are included.                              |
| - ALL COMERCIAL USE IS STRICTLY PERMITED :                            |
|       DON'T SELL WITHOUT PERMISSION OF THE AUTHOR !                   |
|       DON'T INCLUDE IN COMMERCIAL PRODUCTS OR ARCHIVES WITHOUT        |
|       PERMISSION OF THE AUTHOR !                                      |
|                                                                       |
| This  program  is  provided "as is" without warranty of any kind.     |
| The entire risk  of using it is to the user himself.  In no event I   |
| will be liable  for  direct or indirect damage, loss of data or       |
| criminal actions done due to the use of this program.                 |
| If you do not agree with this, you must not use COP.                  |
|                                                                       |
+-----------------------------------------------------------------------+

_____________________________________________________________________________

                         The THOR-Software Licence (v2, 24th June 1998)


This License applies to the computer programs known as "COP". The "Program",
below, refers to such program. The "Archive" refers to the the original and
unmodified package of distribution, as prepared by the author of the Program.


The Program and the data in the archive are freely distributable
under the restrictions stated below, but are also Copyright (c)
Thomas Richter.
Distribution of the Program, the Archive and the data in the Archive by a
commercial organization without written permission from the author to any
third party is prohibited if any payment is made in connection with such
distribution, whether directly (as in payment for a copy of the Program) or
indirectly (as in payment for some service related to the Program, or
payment for some product or service that includes a copy of the Program
"without charge"; these are only examples, and not an exhaustive enumeration
of prohibited activities).


However, the following methods of distribution involving payment shall not
in and of themselves be a violation of this restriction:


(i) Posting the Program on a public access information storage and
retrieval service for which a fee is received for retrieving information
(such as an on-line service), provided that the fee is not
content-dependent (i.e., the fee would be the same for retrieving the same
volume of information consisting of random data).


(ii) Distributing the Program on a CD-ROM, provided that

a) the Archive is reproduced entirely and verbatim on such CD-ROM, including
especially this licence agreement;

b) the CD-ROM is made available to the public for a nominal fee only,

c) a copy of the CD is made available to the author for free except for
shipment costs, and

d) provided further that all information on such CD-ROM is redistributable
for non-commercial purposes without charge.


Redistribution of a modified version of the Archive, the Program or the
contents of the Archive is prohibited in any way, by any organization,
regardless whether commercial or non-commercial. Everything must be kept
together, in original and unmodified form.




Limitations.


THE PROGRAM IS PROVIDED TO YOU "AS IS", WITHOUT WARRANTY. THERE IS NO
WARRANTY FOR THE PROGRAM, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. THE ENTIRE
RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD
THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
SERVICING, REPAIR OR CORRECTION.


IF YOU DO NOT ACCEPT THIS LICENCE, YOU MUST DELETE THE PROGRAM, THE ARCHIVE
AND ALL DATA OF THESE ARCHIVE FROM YOUR STORAGE SYSTEM. YOU ACCEPT THIS
LICENCE BY USING OR REDISTRIBUTING THE PROGRAM.


                                                        Thomas Richter

_____________________________________________________________________________


I) Who should use COP ?
------------------------

- If you prefer working with the workbench or if you write programs in
  pascal or (ARGH) basic, if you do not know how to use an assembler
  or are not familiar with bits and bytes, if you hate command interpreters
  and like funny gadgets and colorful menus, if you do not know the ASCII
  character codes by heart :

  **======================================================**
  || FORGET IT ! STOP NOW ! YOU WON'T BE HAPPY WITH COP ! ||
  **======================================================**

  To make it short: COP is intended to be used by REAL MEN ! (-;
  (or WOMEN...)

        (Suggested: "Real men don't eat quiche" available on
         in good networks...)

II) COP Features
----------------

Let's start with the bad ones:

        o)      it looks like an old-time debugger and feels like one, too
        o)      there's no graphic user interface
        o)      it's based on a command interpreter
        o)      it's hard to learn
        o)      it should support almost all MC68xxx, although I
                haven't tested it
        o)      some features are available only with additional
                hardware, e.g. a MC68010 or higher or an external
                terminal
        o)      some commands are available only with the 2.0 roms or better
        o)      the build-in terminal emulation isn't a fast one
                and uses non-standard command sequences
        o)      it does not handle fragmented memory models in a
                good way, although it's getting better
        o)      there is no trackdisk or harddisk support and there
                never will be
        o)      it does not use task switching, but busy-waits
                (ARGHH!)

        Some of the points WILL change in the future, I promise...


...and now the good ones:
        o)      it does support all members of the MC68000-family,
                at least it should...
                (MC680000 thru MC68060 including FPUs, and MMUs)
        o)      it supports the MMU partially.
        o)      it provides a break key that can be assigned to
                any (well, almost any) key on the keyboard
                and that breaks almost everthing everytime.
        o)      it uses hardware resources as less as possible
                (e.g. no blitter acesses, no copper on request)
        o)      COP can be used to remote-debug a system over a
                serial connection, leaving the display and keyboard
                hardware to other programs
        o)      COP catches almost all system crashes ("GURUs")
        o)      COP can be used to debug almost all code, even
                interrupts are NO problem (is there a second
                debugger that can ?)
        o)      it can be made resident to debug startup code
        o)      it supports symbols in its own language and
                the symbols in object modules. Source level
                debugging, however, is not supported.
        o)      it has a funny documentation in broken english
                (speak you english ?)
        o)      this new release supports printers, connected either to
                the parallel port of your Amiga or to an external terminal,
                provided it supports the new COP 5 terminal standard
                (see terminal.doc in this archive for more information)
        o)      it can be loaded to a memory position of your choice,
                although the arguments are a bit tricky
        o)      it's free, at least this release...
        o)      it steps thru everything, even interrupt code and
                supervisor programs. YES, exec's task scheduler is
                NO PROBLEM AT ALL.
        o)      it can be used as a shell calculator and
                as a label database.
        o)      it supports symbols in standard overlay segments
                (which other debugger does ?)
        o)      it supports debugging of CLI/WB progs in C and BCPL
                thru a simplified interface
        o)      it works in really almost all situations, even
                with execbase broken...
        o)      it supports the ShapeShifter
        o)      it is compatible to the Enforcer and SegTracker if used
                with a MC68020 or MC68030, and to "MuForce" for all
                processors. It might be compatible to Cyberguard, even
                though I won't recommend this program.
        o)      supports the "Picasso96" graphics system. It's currently in the
                "works fine for me" state, feedback welcome.


        ...and if I say "almost all" I mean: more than any other
        debugger can, but I am honest: There are situations where
        COP CAN crash, but they are VERY rare.


III) Before you start, you need to provide...
-----------------------------------------------------------------------------
(or, in other words: NOT included in this package...)

- a lot of good will and your brain. COP is not easy to use...
- this manual. Or to make it clear : READ THIS FIRST BEFORE YOU
  START PLAYING WITH COP. There's a good chance you'll crash your
  system.
- an amiga computer with at least 512K. The more memory, the better.
- If you want that magic break feature : A processor MC68010 or
  higher would be fine. The break key does not work in all situations
  with the standard MC68000.
- If you need all commands (e.g. task capture and task freeze), you need
  commodore's 2.0 roms or better.
- If the program to debug requires the display subsystem, you need at least
  an external serial tty terminal - this is the recommended way to debug
  programs anyways.
- If you want a fancier and better user interface, the external terminal
  should understand type-3 terminal commands or better. Cause this is
  a private format, there are not many... :-)
  You may write your own terminal, or use the one supplied in this
  package, see "terminal.doc".
- If you need printer output, you need either a printer connected to the
  parallel port of your Amiga or a printer connected to an external type-5
  terminal or tty-terminal with printer-support. Any printer will do, COP
  outputs only plain 7-bit ASCII.
  Use the following configuration for your printer:

        o) data input from parallel interface
        o) Auto-LF on, CR disabled (Auto-CR does not care)

  This is, however, the most common setting, so just try. The normal setting
  will work in most situations without any change.

  If you MUST use the Amiga parallel port, use the command line switch
  BUILDINPRT or the IOCD.Q command to disable external printing.

  The current version of COP is not able to debug a program via the parallel
  port, though. It's exclusively reserved for printer output. If your program
  requires the serial port, use the build-in terminal emulation.


IV) Installing COP in your system
-----------------------------------------------------------------------------

If you want to remote-debug your system: connect an external ASCII-terminal
to the serial plug. Set the external terminal to the following parameters:

9600 baud, 8 bit, 1 stop bit, no parity,
no auto LF, no auto CR, non-erasing BS

If your external terminal supports printers, connect the printer to THIS
terminal, not to the Amiga; if not, connect the printer to the parallel port
of the Amiga and use the IOCD.Q command or the command line option
BUILDINPRT to tell COP to use the build-in printer-routines.

Copy the COP file to the C:-drawer of your system disk and, if you like to
start COP from the workbench, copy the COP-icon anywhere you want (this is
not required, only a nice feature ).

Copy the shell scripts "Debug","WBDebug" and "Calc" to the S: drawer,
put this file in a save place wherever you want.

If you have commodore's V40 includes, copy the default data description
table "Startup.DDT" to S:. You might want to modify it a bit, for example
to correct the paths. This file currently expects the FD files in a
device FD:, and the includes in INCLUDE:

If you want to run COP with the shapeshifter, copy the file "Mac.DDT" to
S:, too.

Insert in your startup-sequence DIRECTLY FOLLOWING to the "SetPatch"-command
(this is the second line for most systems) a command like the following:

COP keymap usa display resident ddt s:startup.ddt pre s:startup.pre

If you own a 040 or 060 based system, you should specify the "NOMMU" and
"NOEMU" options as well.

What does this mean:
-The build-in terminal uses the keymap "usa". If you prefer a different
 keymap, change "usa" to your favourite keymap - it must be present in
 the DEVS:keymaps drawer of your system.
 YOU CAN'T CHANGE THAT KEYMAP WITH A "SETMAP" or "SETKEYBOARD" or the
 PREFERENCE PROGRAM LATER !
 COP OPERATES INDEPENDED FROM THE REMAINDING SYSTEM !

-The "display" command tells COP to use the build-in terminal instead of an
 external one. You can debug programs with the amiga keyboard on the amiga
 monitor. If you want to remote-debug, use "serial" instead. If you've got
 an external tty, I would suggest to do so.

-The "resident" keyword tells COP to stay resident even after reset. If
 you do not need this feature: drop this argument. Loading COP as resident
 program has the advantage that you can debug boot code.

-The "ddt" keyword loads the standard labels placed in the ddt-file and
 commodore's include files into COP. If you don't have them:
 Never mind, just delete the the last two arguments.

-The "pre" keyword instructs COP to build a pre-compiled image of the "ddt"
file on first startup - they are faster to load and speed up booting. If
you're low on disk space, drop this argument.

-The "nommu" keyword for 040 and 060 systems tell COP not to touch the MMU
unnecessary. The MMU is required for these systems to guarantee reliable
DMA access.

- The "noemu" keyword avoids catching of emulator traps for unimplemented
040 and 060 FPU instructions.

More about the command argument line later... (chapter XI)

You should also start the workbench with the "-debug" option to have COP
ready in all situations.

For professional debugging, you should also install "MuForce" by the
same author, and "SegTracker" and "MungWall", all by Michael Sinz. "MuForce"
is supported by COP, bus errors are routed thru COP, though. The "SegTracker"
is used by COP to find the segment/offset information of a crashed program.

Save the modified startup-sequence and reboot your system. Not much to
see? O.K., that's normal. COP is NOT a standard debugger and is only
INSTALLED by the command line, but not STARTED.



V) How to start COP
-----------------------------------------------------------------------------

There are many ways to begin a debug session with COP:
-Double-click the COP-Icon, if you copied it to your system.
-Enter in the shell the command:

        COP go

-Select the "ROMWack" (or "Debug") menu of the workbench. COP replaces
 the old wack completly, if there was one installed in your ROM.
 (Commodore removed the old ROM-Wack from the 3.1 Roms and replaced it
 with the "SAD" debugger.)
-Press the BREAK-key. In the build-in terminal - if you gave the
 "display" argument above - this is the decimal dot of the numeric key-
 pad. On external terminals, it's ESC. However, you may change that key
 with an additional argument, see chapter XI.
-Use the shell-scripts "Debug" and "WBDebug" to load programs,
 symbols and start a debug session like with every other debugger.
 Up to eight arguments are allowed here as CLI arguments, resp. one as
 an extended selection icon "shift-selected" with the main icon.
-The least pleasant way : Your system crashes and COP is entered auto-
 matically. There are NO GURUs any longer, COP catches them all !
 (Well, almost all... A special DOS crash isn't routed thru the standard
  system requesters and can't be captured by COP - sigh.)
 If you supply a data description file (see below), you even get the
 guru codes in a readable language. If you installed "SegTracker", too,
 COP will also present the name, the segment number and the segment offset
 of the code that crashed.


VI) How to leave COP
-----------------------------------------------------------------------------

Enter GOPG in the COP command line and press RETURN. This should start
the program interrupted.
If you entered COP by a guru, you should first debug the system or will
get just another guru in mostly all cases. There's no good strategy to
accomplish this task....

You may also start the old ROMWack from inside COP with the EXIT command.
Starting with ROM versions 3.0, the system debugger has changed to the
(more primitive ? different ?) SAD.
See the autodocs how to use this thing...


VII) A word about COP-terminals
-----------------------------------------------------------------------------

You will normally use COP's build-in terminal to debug code, but this
terminal will, of course, need some of the hardware systems - the display
system, i.e. the copper and the display DMA channels (not the blitter),
and the keyboard, also the parallel port if you want to print.
I tried to implement the terminal as best as possible, but this may
conflict with other programs which want to use the same hardware resources.
For this reason COP can also be used to debug a system via the serial port.
All you need - for the minimum configuration - is an external
ASCII-terminal,e.g. a second amiga with a standard terminal program will
do it.

In this case, choose the following transfer options:

9600 baud, 8 bit, 1 stop bit, no parity

no auto CR, no auto LF, nonerasing BS


However, things are much easier if you use a terminal program providing
COP's private terminal formats, here called "type-3" or better terminals.
The terminal transfer standard is documented in the "Terminal.doc" file
in this drawer, if you want to write your own program. There are only
two ready made programs supporting this standard:

-THOR's "Terminal" program for all Amigas provides a type-4 terminal
 emulation and is included in this drawer.

 Enable the "COP Terminal Emulation" from the menu Settings/Protocol.
 You also need to supply a null-modem connector, but you should know
 how to build one...

-THOR's "DASB" terminal is a full type-5 terminal, working on
 Atari 800XL computers with a serial interface box. It's included
 in the package.
 There are no settings to be made, DASB is written exclusively to communicate
 with COP, but does not support a printer. This drawback arises from the
 Atari XL hardware.

If you want to write a COP terminal on your own (e.g for a C64) you
are welcome! Please send me an email in this case (address below).

The build-in terminal for non-remove debugging is of course a full
type-5 terminal.


Here a word about the keyboard processor of the build-in terminal:

I tried to write a keyboard parser not conflicting with other
applications, i.e. it does not read the IRQ-registers of the CIA-
chips and is able to work even with all interrupts disabled. However,
there are "some" drawbacks of this magic stuff : Sometimes a key
may "leak thru" the keyboard parser to other applications. Because
the corresponding key-up event is missing, the keyboard device will
then activate the auto-repeat loop and generate a stream of key-events.
If this happens, leave COP and press the repeating key to stop it.
Even worse, you won't recognise this bug if the affected key is a
control key like "Ctrl" or "Shift". If, after leaving COP, the key-
board seems to be out of order, try pressing all this keys first to
send their key-up events. I tried hard to fix this bug, but it looks
like there's no better way to write a magic keyboard parser. If you
want to use COP the professional way, you should work with an external
terminal anyhow.


VIII) How to enter commands, the line editor
-----------------------------------------------------------------------------

Once you've entered COP, it presents you the prompt "COP >" and is ready
to accept debug commands. Below the special keys used for line editing:

-The backspace key erases the last character entered and moves the
 cursor backwards one line ("Delete" on some terminal). On some terminals,
 Ctrl-H must be used as a substitution.
-The delete key ("rub-out" on some terminals, Ctrl-Backspace with
 DASB, not available on all terminals) deletes the character under the
 cursor and scrolls the rest of the line backwards.
-The return key starts the execution of the command ("Enter" on some
 keyboards)
-Ctrl-C aborts the execution of a command.
-Ctrl-U re-displays the last command entered - there's only a two-line
 history for commands, identical and empty lines will not enter the history.
-The decimal dot on the numeric keypad (for the build-in terminal) or
 the ESC-key on external terminals stops execution of code and enters
 COP. However, this break feature wouldn't work if all interrupts are
 disabled or, if you use the MC68000, the interrupt vectors are messed
 up.
-The cursor-forward-key moves the cursor forward one character (only
 type-3 or higher terminals)
-The cursor-backward-key moves the cursor backwards one character
 (only type-3 and better)
-The cursor-up key moves the cursor to the begin of the line (type-3
 and better only)
 As a replacement, Ctrl-A can be used for this task with TTY-terminals.
-The cursor-down key moves the cursor to the end of the line (type-3
 and better only)
 A replacement for this key is Ctrl-E.
-The Alt-Del key or Ctrl-Clear (with DASB) erases the whole line
 (type-3 only). This feature is available with Ctrl-B on all ASCII
 terminals.
-The TAB-key has a special meaning while entering data sequences and
 is described below.


IX) The COP commands and expressions
-----------------------------------------------------------------------------

Each COP command looks like the following:

- a semicolon ";" followed by a comment, or

- a four character command base name or a one character short-cut
- optionally a dot and an extension that determinates a specific
  sub-command of a larger command class
- optional arguments each separated by space(s)
- optionally a semicolon followed by a comment

ALL numbers accepted by COP MUST BE GIVEN IN HEXADECIMAL, all arguments
may contain simple calculations with numerical operators. This will be
called an EXPRESSION in the following, abbreviated with <expr>.
Here all supported operators, listed by their priority from low to high
(higher priorities are evaluated FIRST, please note that the priorities
 differ from C - in special the shift operators):

$               trap operator
                a$b returns a if b is faulty, else a.
                NOTE: You cannot enclose $ in brackets, so expressions like
                (2$a+b)-3 are ILLEGAL !
                The reason for this is that COP can't continue to evaluate
                expressions with illegal syntax that will be trapped by $

?,:             C-style condition operator:
                a?b:c returns b if a is not equal, else c

=,<>            equal, not equal: returns -1 if expressions to the
                right and left are equal (resp. not equal) or 0 otherwise.

>,>=,<,<=       signed greater, greater equal, smaller, smaller equal.
                Returns -1 if the condition is true.

|               binary or
!               binary or
^               binary exclusive or (XOR)
&               binary and

+,-             addition, subtraction

>>,<<           shift left or right. The left expression is shifted
                times the right expression

*,/,%           multiplication, integer division, modulo

[..]            indirect operator: the value is the (long) content of
                the address specified by the expression between the
                braces, e.g. [4] is ExecBase.
[..].l          same as [..]
[..].w          indirect operator, returns the (sign extended) value of
                the word at the address in braces
[..].b          indirect operator, returns the (sign extended) value of
                the byte at the given address
[..].o          the operator size is determinated by the instruction under
                the program counter.

                NOTE: There is a slight difference if you read a word or a
                long from an even or odd address. Reading from an even
                address is only ONE memory access, but reading from an odd
                one are TWO or FOUR accesses. While not a problem to normal
                memory, this is a difference for hardware registers !

(..)            normal brackets: expression in the brackets is
                evaluated first
-               unary minus, i.e. change of sign
~               unary not
>               unary greater. This symbol contains the last address
                affected by COP and is called the "here" address pointer.
                It is affected by almost all commands and can be used
                for saying the new command should "work on the same
                address" as the last one.
*               unary star. This symbol contains the program counter of
                the CPU and is equivalent to ".pc"
.b,.w,.l,.o     Sign extension operators. Will interpret the preceding ex-
                pression as byte, word or long and sign-extend it.
                So $ff.b is -1, but $ff.w is $000000ff.
                The .o is again the sign-extension to the operator size
                of the instruction under the PC.
                There is a small, but noticable difference between
                [adr].b and ([adr]).b ! The first will read only ONE BYTE
                from memory, the later FOUR BYTES but throwing away three
                of them. This DOES make a difference if you read a
                hardware-register !
.reg
 or
'reg            The content of the CPU register .reg
or              Valid registers are .d0 to .d7 for CPU data registers,
reg             .a0 to .a7 for address registers - note that the
                meaning of .a7 changes with the supervisor bit -
                .ssp and .usp for the two stack pointers
                .pc (same as *) for program counter and .sr for the
                status register (there is NO .ccr, use proper masking).
                Also, there are 16 COP internal counter registers
                .c0 to .cf. They are incremented each time they are
                read and can be used to implement counter breakpoints.
                For some commands .fp0 to .fp7 are valid and address
                the eight FPU registers, if a FPU is installed and
                used by the program debugged.
                All other CPU/MMU/FPU registers are available in the same
                way, with one tiny exception for the MMU "root pointer"
                registers. These two registers are 64 bit wide for the
                68020/68851 and 68030 CPU/MMU and only the lowest long word
                containing the base address of the MMU table is read.
                If any of the MMU root pointers are written to, the high
                long word is set to $80000002, i.e. to setup a short
                descriptor MMU table. This is the standard way how the MMU
                is used and I haven't seen any program that uses MMU
                tables with long descriptors.
.sr,.se,.so
.dr,.de,.do
                These pseudo registers refer to the source and
                destination effective address of the command under
                the program counter.

                .sr     is the contents of the source register under
                        the PC, if available
                .se     is the effective address of the source operand,
                        if available
                .so     is either the content of the source register or
                        the CONTENT of the effective source address
                .dr,.de,.do
                        Same for destination effective address
                You may alter all these registers to effect the source
                or destination operand of an instruction. Although not
                causing an error, changing .se and .de does nothing
                usefull.

                (Note: This feature is not yet implemented).

                Additional, all supervisor registers of the 680x0 series
                can be viewed, as long as your CPU does support them,
                and will be written back as well as soon as you restart
                the program. However, read the special caveats about the
                MMU root pointers above. (Except that you shouldn't mess
                with the MMU anyways except you're perfectly sure what
                you're doing.)

                A new special register .vvbr has been introduced
                in release 1.32:

                The .vbr register refers always to the VBR of the CPU,
                but since COP needs this register to operate properly,
                you should not change VBR this way. Whenever possible,
                check the value of VBR, and if it has changed, write
                the new value not to VBR. Use the VVBR instead, and
                restore VBR to the value of the label COPVBR. COP will
                then filter out its own exceptions and pass the unused
                back to the system thru VVBR as if the VBR has been set.

                The change of VBR will now be detected by COP if the
                interupt check (ENVI.I) is turned on, and the VBR register
                can be restored by SETR.V. The autovector table can be
                rebuild automatically using the IRQ-copyback mode, enabled
                with the ENVI.C command.

\character      The ASCII-code of the character following

$               Unary $. The number following is given in hexadecimal
                AS THIS IS THE DEFAULT, THIS SYMBOL DOES NOTHING

#               The number following is given in decimal, i.e.
                #16=$10=10

%               The next number is a binary number, i.e.
                %1000=$4=#4=4

label           A known label will be evaluated. By default there are
                only four labels:

                AbsExecBase     will contain the value 4, thus is
                                pointing to the pointer of the system
                                library.
                Version         Will contain the version of COP as
                                Version<<16+Revision
                COPVBR          will contain the interal vector base
                                setup by COP. VBR should contain this
                                value.
                                DO NOT ALTER COP's vector base, use
                                VVBR instead.
                COPVVBR         will contain the default position of
                                COPs virtual vector base.

        Some read-only expressions follow:
        (Not starting with a dot -> Not a (pseudo) register -> not alter-
         able !)

l0              Left button of mouse or fire on joysticks connected to
                port 0, returns 0 if released or -1 if pressed
l1              same for port 1
                l0 and l1 might be quite useful as conditions in
                breakpoints
r0,r1           Right button of mouse in port 0 or 1
m0,m1           Middle button of mouse in port 0 or 1
        WARNING ! Some hardware limitation cause that it takes max.
        20 msecs to read r0,r1,m0,m1. This COULD be made somewhat faster,
        but nevertheless r0,r1,m0,m1 ARE NOT FAST ENOUGH TO BE USED IN
        CONDITIONED BREAKPOINTS.
        Reading them causes also the POTGO-hardware register to be trashed.
        There is no way to save this register back, although
        there is a POTGO-read register - this is a hardware limitation.

su,sr           Information about addressing mode under the PC. su and du are
du,dr           TRUE if the source resp. destination operator of the actual
                instruction is used, sr and dr return TRUE if it is a register
                and FALSE if it is in memory.
                (This is actually not yet implemented)

op              Data type of the instruction under the PC, returns
                0 for byte, 1 for word or 2 for long, so 1<<op is the
                size in bytes of the operator.
                (This is actually not yet implemented)


X) List of all commands
-----------------------------------------------------------------------------

Long command    Short command   possible extensions     arguments

HELP            ?               none                    none
                prints all COP commands to the active terminal

EXIT            X               none                    none
                If execbase valid, COP is terminated and the
                ROMWack is entered. Note that ROMWack works ONLY
                with an external terminal (if there is one... it
                has been removed from the 3.1 - V40 roms).

REGS            R               G,E,C,A                 none
                Register dump commands

                Without extension:      Dumps all common CPU
                registers to the screen, dumps fpu registers
                if FPU is available and in use.

                REGS.G                  Dumps the guru number
                and the address that generated the crash. If COP
                was entered the normal way, the guru number will
                be zero.
                If a data description table was loaded and
                gurus were defined, the full name of the
                guru will be printed.
                If the "SegTracker" is available, COP will print the
                name of the crashing program and the segment/offset
                location of the PC within this program.

                REGS.E                  Dumps special purpose
                registers of newer members of the MC68000 family as
                cache-control and MMU-registers. FPU registers will
                be included if the FPU is available and in use.

                REGS.C                  Dumps the COP-internal
                counter registers (without being incremented)

                REGS.A                  Dumps effective address
                of instruction under PC and memory contents, if
                available.

DUMP            D               B,W,L,C,S,G,H,I,Q,Z,D,X,P,O     <expr>
                Dump memory. If <expr> is omitted, then the "here"
                pointer is used as address, otherwise change "here"
                to the given <expr>.

                without extension       Dump memory in the last mode
                used

                DUMP.B                  dump memory as bytes
                DUMP.W                  dump memory as words
                DUMP.L                  dump memory as longs
                DUMP.G                  dump a sequence of hardware
                                        bytes. The memory manager gets
                                        overridden by mode.
                                        ! This might be somewhat danger-
                                          ous, if you read some toggle
                                          registers !
                DUMP.H                  dump hardware word
                DUMP.I                  dump hardware long
                DUMP.Q                  dump as quad word (=8 bytes)
                DUMP.Z                  dump as single precision
                                        IEEE-numbers.
                DUMP.D                  dump as IEEE double precision
                DUMP.X                  dump as MC68881 extended precision
                DUMP.P                  dump as MC68881 packed decimal
                DUMP.O                  dump memory as size of instruction
                                        under PC

                DUMP.C                  Dump memory as characters.
                All unprintable characters are transcribed with a
                backslash and the numerical hex value followed.

                DUMP.S                  Dump memory as strings.
                All unprintable characters are displayed as a dot.


                After dumping a few lines, COP stops and asks you
                to press RETURN or SPACE to continue. You may press
                here Q or Ctrl-C to abort dumping.


EDIT            E               B,W,L,C,G,H,I,Z,D,X,P,O         <expr>
                Edit memory or hardware. If <expr> is omitted, then
                edit the address given by the "here" pointer. Else
                use the <expr> as address and save it to "here".

                In the edit mode, COP presents you the old contents
                of the address given. This value is now ready to be
                changed with the edit keys (see the last chapter).
                Press RETURN to accept the changes made or press TAB
                to undo the changes. Press Ctrl-C to abort editing.

                BE WARNED! The string "d0" means "contents of register
                d0" not the value "d0", like everywhere in COP. To enter
                the value "d0", you've to type "$d0". Quite for the same
                reason we've "cf" as "contents of counter #f, increment it
                when read" and not "the number $cf". The later is "$cf".


                Without extension       use the last edit mode used
                EDIT.B                  edit memory as bytes
                EDIT.W                  edit memory as words
                EDIT.L                  edit memory as longwords
                EDIT.Z                  edit as IEEE single precision
                EDIT.D                  edit as IEEE double precision
                EDIT.X                  edit as MC68881 extended precision
                EDIT.P                  edit as MC68881 packed decimal
                EDIT.O                  edit memory as size of instruction
                                        under PC

                EDIT.G                  set hardware as bytes
                EDIT.H                  set hardware as words
                EDIT.I                  set hardware as longwords

                The difference between the first group and the second
                is that the hardware edit commands do NOT read the
                hardware registers prior to the user change. Instead,
                a zero gets displayed. Node that this is necessary because
                some hardware registers are WRITE ONLY.
                In all the modes presented above, you may enter a full
                <expr> as well as a numeric constant as a new value,
                although the length of the <expr> is limited.

                EDIT.C                  edit memory as characters

                Here, you may edit the memory as ASCII-characters. You
                may use the backslash followed by a hex number to enter
                values not available on the keyboard.

EVAL            =               none                    <expr>
                Evaluate the expression given and print the result.
                The result might be a simple number, but very complex
                expressions including labels are valid, too.

UNAS            =               none                    <expr>
                Unassemble code starting with address <expr> and set
                "here" to this value. If <expr> is missing, disassemble
                at address contained in "here".

                The disassembler knows the obcodes of all members of the
                Motorola MC68000 family, but the non-MC68000 codes are
                marked. FPU obcodes are disassembled as well, and numerical
                constants will be disassembled as decimal floating point
                expressions.
                Illegal opcodes or opcodes that can't be used on the Amiga
                (like the TAS instruction) get marked as well.

                Depending on your enviroment settings - see the ENVI comand
                - some of the addresses will be expanded to known labels.

                NOTE: I was unable to test the correct disassembly of the
                MMU and MC68040 codes, although it SHOULD work.

                If the address being disassembled is the PC, this line
                is marked with an asterisk *; if it's the "here" pointer,
                the line is marked with ">".
                If the address is affected by a break point, a "B" is
                inserted.

NODE            N               L                        <expr>
                Display the node at address <expr>. If <expr> is not
                present, use the "here" pointer, otherwise set "here"
                to the address of the node.

                No extensions        The name of the node and its type
                is displayed.

                L            Dump the node as before, but print
                additional information COP can gain about that node. COP
                knowns most node types defined in the Os and will print
                additional information contained in the data attached to
                the node.



LIST            L               M,R,D,I,L,P,T,S,Q,B     <expr>
                Dump contents of exec-type lists.

                No extension            Dump the list at given address,
                set "here" to this address. If <expr> is omitted, use
                the "here" pointer.

                B                       Same as without extension, but
                the list is traversed from the last element to the
                first. This is sometimes useful if parts of the list
                are broken.

                M                       Print exec memory list
                R                       Print resources
                D                       Print loaded devices
                I                       Print software interrupts
                L                       Print libraries
                P                       Print ports
                T                       Print tasks
                S                       Print semaphores
                Q                       Print hardware interrupts


FILL            F               M                       <expr>,<expr>
                Fill memory with byte sequence starting with first <expr>
                and to last <expr>, exclusive. If one of the <expr> is
                missing, then "here" is used. Then "here" is set to the
                first <expr>.

                without extension       Enter the byte pattern the memory
                should be filled with. Press TAB to complete one byte, press
                RETURN to complete the whole sequence and to start filling.

                Again, "d0" is the register, not the value. The number is
                entered as "$d0".

                M                       Fill memory thru mask (stencil
                fill operation).        Enter first the byte sequence
                as described above, then enter the mask bytes. Each
                bit set to zero in the mask will protect the corresponding
                memory bit from a change.

                You may press Ctrl-C any time to abort the operation.


FIND            I               M,I                     <expr>
                Find byte pattern, masked, or find instruction starting
                with given address or "here". Set "here" to given
                expression afterwards.

                The found values are either dumped in the last mode used
                by the "dump" command, or disassembled with the "I" mode.

                Furthermore, if the display is split, COP stops the search
                as soon as something is found and updates the top window
                of its screen, with the "here" pointer set to the found
                address. This is most useful for displaying a large area
                around the found bytes, and can be optained by displaying
                the output of a command like "d >-8" in the top window.
                To remind you, ">" is the name for the "here" pointer.
                More about display splitting is found below.


                without extension       Enter the byte pattern byte for
                byte pressing TAB after each byte and RETURN to complete
                the sequence you are searching for.

                See above for caveats! "d0" is a register, not a number!

                M                       Find masked. Enter the byte pattern
                you are searching for and then the mask.
                Each bit left to zero in the mask will disable the
                comparision of the corresponding bit in the sequence, i.e.
                the corresponding bit in the byte pattern will be ignored
                and will match always.

                I                       Find instruction. Enter the
                instruction or part of instruction you want to search
                for and press RETURN to start the search. Case and extra
                spaces will be ignored.
                You should note that all known labels will be expanded
                by COP unless the enviroment is changed. So you should
                enter the label names instead of the address if you look
                for an access to a defined label !

                You may press Ctrl-C to abort the searching at any time.



MOVE            M               none                    <expr>,<expr>,<expr>
                Move source memory block starting with first <expr> and
                ending with second argument exclusive to destination
                given by last <expr>. If any of the <expr> is missing,
                "here" will be used. Afterwards, "here" is set to the
                start of the source memory block.
                Overlapping memory blocks will be handled correctly.

                You may press Ctrl-C to abort the operation.


TASK            !               F,W,S                   <expr>
                Task commands: display,freeze and warm tasks, send
                signals.

                without extension       Display information about the task
                if <expr> is omitted and execbase is valid, the active task
                will be displayed.

                F                       Freeze the given task (exclude from
                execution). If the task to be freezed is the active one,
                this command will work with Kickstart releases 2.0 or higher
                only.

                W                       Warm the given task (include a
                previously freezed task in task switching).

                S                       Send a signal to a task. You need to
                supply two arguments, FIRST the signal to be send and
                SECONDLY the task affected.



SETR            S               F,E,D,V                  <expr>,reg
                Set <expr> to given CPU register.

                without extension       Move given expression to a
                destination register. All CPU registers are valid
                destinations, but only the low long word of the 64 bit
                wide MMU registers of the 68851/68030 will be set, their
                high-longword will be set to $80000002 always. This
                word is just a dummy for the 68040 and 68060, but used
                to identify the size of the descriptors and a "limit" value
                for the 68851/68030. However, I don't remember any program
                that makes actually use of these extensions.

                If you need to change the vector basis register VBR
                of 68010 or above, you should change COP's virtual
                VBR called .vvbr instead to keep COP's exception
                vectors untouched.

                F                       Load FPU register, if FPU is
                available and in use by the program being debugged.
                In this case, <expr> is a floating point number in the
                usual notation (e.g. 3.1415 or 3E8 ...).


                E                       With MC68020 or higher: enable
                all caches. No arguments need to be supplied.

                Warning: Don't touch the cache for 68040 or 68060 systems,
                at least don't try to activate it by force if it is not
                activated. DMA related device I/O might break by enabling
                the cache in an I/O operation.

                D                       With MC68020 or higher: disable
                all caches. No arguments taken.

                Cache finetuning, if required, should be done by modifying
                the cacr register directly.

                V                       With MC68020 or higher: Set the
                virtual vector base address to VBR, setup VBR to point
                to COPs interrupt vector table. This command should be
                given (if it isn't already too late...) if a program
                changes the VBR to give back control to COP.

STEP            Z               none                    <expr>
                Enter trace mode, start tracing at given address or use
                PC if <expr> is omitted.
                How the trace mode works depends highly on the terminal
                type used to debug.
                On pure ASCII-terminals, the command at the PC is being
                disassembled and dumped to the terminal; on type-3 or
                type-4 terminals however, an entire page of instructions
                is printed. The command at the PC is marked with an
                asterisk and is highlighted on type-4 terminals. Lines
                with breakpoints are marked with a "B". The current
                position of the "here" pointer is marked by ">".

                With both types of terminals, COP is now ready to accept
                one of the following step commands by pressing the
                desired key:

                Q or Ctrl-C     Abort trace mode and return to normal
                command line.

                S or SPACE      Step the command at the PC. If this is a
                subroutine call, the subroutine itself will be entered in
                trace mode and can be stepped thru.

                T               Trace the next command. The only difference
                between S and T is how subroutines are handled. With the T
                command, the subroutine is called as it and will be exe-
                cuted as whole without beeing stepped thru.

                N               Next command. Almost like T, but works
                different with branches. The next command starts the program
                at the current PC and COP regains control only if the
                statement IMMEDIATLY FOLLOWING the traced statement gets
                executed. This will be the same as T for all commands but
                branch and jump commands. You may use N to step thru a
                loop as whole if you press N for the end condition branch
                of a loop.
                WARNING !!      If this loop has a second exit point, the
                command after the end condition may never be executed and
                COP is never entered again.
                WARNING !!      The next command works ONLY IF THE STATE-
                MENT IS IN RAM CODE and DOES CHANGE parts of the code by
                setting an internal breakpoint. See BRKP-section for a list
                of caveats of breakpoints.

                M               Trace until. Almost like T, but the mecanism
                how COP regains control after a subroutine call is different.
                The 'T' trace changes the return address to COP's entrypoint.
                Sometimes this is unwise cause this address might get used
                by the called procedure. If you use 'M' instead, the called
                procedure will be stepped thru in 'S'-like behaivor using
                the CPU's trace-bit. Of course, 'M' will be much slower
                and should not be used if some piece of hardware is accessed
                or timing is vital.

                O               Skip command. Do not execute the command
                at the PC and switch PC to the command following.
                WARNING !!      Make sure that the command skipped does
                not anything important and watch out for side effects,
                e.g. skipping a "push long to stack" could be dangerous
                if the corresponding stack cleanup command is not skipped
                too.

                G               Start program at current PC, activate all
                breakpoints.

                R               Dump registers to terminal.

                B               Set breakpoint at current PC address.
                Note that commands with a breakpoint on it are marked
                with a "B". Further, a breakpoint under the current PC
                is "delayed", i.e. it isn't activated unil the the PC
                leaves its address.
                The breakpoint set by "B" will be an unconditioned type
                (see BRKP for more about breakpoints)

                A               Alter display. If working with the build-
                in terminal, the COP display is hidden and the display of
                the program is brought to the monitor. The "A" command
                is like the "IOCD" command without extension, read this
                chapter to find more about COP displays.
                If you use the remote-debug feature, this command does
                nothing.

                F               Set COP to foreground mode, i.e. COP does
                not hide its display if the program being debugged re-
                gains control. Press F again to activate the normal display
                swapping. This command works mostly like the "IOCD.F"
                command, read the "IOCD" section for more information about
                COP foreground and background mode.


                Some caveats about tracing are:
                -------------------------------

                - COP does not depend on exec-like task switching, it
                is NO PROBLEM to step thru exec's task switching procedure.
                (This is actually not a caveat !)
                On the one hand a nice feature, on the other hand a problem
                if you want to debug a SPECIFIC task. Therefore, you should
                trace (T command) over a Wait() or Signal() call of exec.
                The NEXT (N command) will work too, but if the same code
                is used by two tasks - think about the trackdisk code - you
                may catch a different task afterwards. Same goes for the
                'M' command, but let me remind you again that 'M' is SLOW !

                -The second problem with task switching is that if an exec
                task looses control by stepping thru the task-switch
                routine, exec will save its status register with the trace
                bit on. If the task is reactivated later, COP will regain
                control over this task. While not a problem to COP, this
                behaviour might somewhat confusing to you, if COP is
                suddenly (probably after hours...) reentered - and not by a
                guru.
                -There's one extra problem with the trace (T) command :
                This commands works by altering the return-address of a
                subroutine call. Some programs use this return address to
                fetch data following the subroutine call and adjust the
                return address afterwards. If changed by COP, this
                will cause a nice crash of your system. Thus, if you find
                funny code behind a subroutine call, e.g. many illegals
                or the like, STEP thru this procedure or use 'M'.
                -Since stepping thru a procedure is much slower than
                executing one, there may arise timing problems in some
                critical IO-procedures. You should trace this kind of
                subroutines to avoid such problems. This goes again for
                the 'M' command, since this is nothing but "automated
                stepping".

                (That looks like a lot of "features" of this debugger,
                but they are typically for this class of programs.
                However, most authors handle them as "undocumented
                features", but I don't. :-) )


BRKP            B               A,D,C,R,S,O             <expr>
                Breakpoint commands. The address affected is given by
                <expr> or by "here", if omitted.

                without extension       If no breakpoint is set at
                supplied address, a unconditioned breakpoint is set there.
                If a breakpoint is set at this address, the breakpoint
                is removed. Note that COP supports up to 32 breakpoints.
                It is further important to note that after setting a
                breakpoint, it is not yet active, i.e. causes a COP inter-
                cept. The breakpoints are activated each time a program is
                restarted, e.g. with the GOPG command; they will get de-
                activated each time COP is entered again to prevent an
                endless loop if a breakpoint is set in interrupt code.
                However, the breakpoints can be activated by hand, although
                this is not recommended.


                BRKP.A                  Remove all breakpoints (no
                arguments accepted)

                BRKP.D                  Display all set breakpoints
                with conditions, no arguments accecpted.

                BRKP.C                  Clear breakpoint at given address

                BRKP.R                  Reset all COP counter registers
                .c0 to .cf to zero.


                BRKP.S                  Set breakpoint at given address
                and condition, if any. If the condition is omitted, then
                an unconditioned breakpoint is set. If a counter
                register is included in the condition, it is reset to zero.

                With a conditioned breakpoint COP is entered on a BREAK
                hit only if the condition is true, i.e. not zero.
                You should remember that a counter register is incremented
                each time it is accessed, so you may use this feature
                to implement counter breakpoints, e.g. ".c0>=5" will stop
                execution after the fifth BREAK-hit.

                BRKP.O                  Activate all breakpoints (no
                arguments accepted). Note that this operation might
                somewhat dangerous if a breakpoint in an interrupt
                procedure gets activated. In this case, COP will display
                its "COP crashed" or "Other Task Crashed" message...
                have fun!

                Some extra features of breakpoints are the "delay" of
                breakpoints and the automatic removal of them:
                -If you set a breakpoint under the current PC, this
                breakpoint won't get active if you start the program,
                but gets activated AFTER the PC leaves the statement.
                This is useful cause you usually never want to break
                on a command you already broke on. You will enter COP
                when the program reaches the breakpoint again.
                -If an already activated breakpoint is getting written
                over by a program (e.g. the memory is freed and another
                task re-uses this area), this breakpoint is REMOVED
                automatically at the time COP is entered again.
                This is done to prevent programs from crashing by dangling
                breakpoints of a program that is no longer in memory.

                WARNING !       The breakpoint IS NOT removed, if it
                is not active at the time it is written over.
                This MAY cause problems if the program changes and the
                breakpoint is re-activated later, e.g. the breakpoint
                may change the address part of a jump-instructions,
                possible resulting in a nice fireworks display...

                WARNING !       Active breakpoints change the code
                at their address to the ILLEGAL obcode. For this,
                BREAKPOINTS DO NOT WORK IN ROM.
                (Trick for MMU owners if you need to do this: Enable
                 the MMU bypass and set the breakpoint in the mirrored
                 RAM.)
                Second, if the code is changed, possibly some check-
                sums (for libraries or resident code) will change and
                things won't work later. For this reason, use the
                T S or M STEP subcommands to step thru this part of code,
                they DO NOT ALTER the code and work in RAM as well as in
                ROM.




GOPG            G               U,T                     <expr>,<expr>

                without extension       Start interrupted program at given
                address or at PC if <expr> is omitted. If any breakpoints
                are set, activate them first. A second argument is not
                accepted.

                U                       Go until
                Set a breakpoint at the first given <expr> and start
                the program at the address given by the second argument,
                or the PC if omitted. Read the breakpoint section about
                caveats of breakpoints !

                T                       Trace until
                Step thru the program until the PC reaches the first
                expression. The second expression will be loaded into the
                PC if given. This will be very slow, like the 'M' sub-
                command of STEP.


CAPT            C               S,N,C                     [<expr>,]<expr>
                Capture a task, i.e. start debugging it.

                no extension            Capture the task with task
                structure at the supplied address. If <expr> is omitted,
                "here" is used. Afterwards, "here" is set to the
                affected task address. If the task uses the FPU,
                this capture command will work only with Kickstart
                release 2.0 or later, due to the private exec stack frame
                which has been changed in Rev. 2.0.

                S                       Like capture without arguments,
                but the first argument you supply is a signal mask which
                is send to the task before trying to capture it. The
                second argument is the address of the task structure.

                N                       Capture the next task getting
                started. No argument must be supplied with this sub-
                command. Note that you might find the new task in the
                private dos startup code you have to step thru first.

                C                       Capture next command getting
                started from the shell. This command works only with
                Kickstart 2.0 or later.



IOCD            O               S,C,B,F,R,Z,L,M,V,P,Q,I,E      <expr>

                Input / output commands, terminal commands (rather a
                lot of them...)

                without extension       (does not take any arguments)
                If you work with COP's build in terminal, toggle between
                COP's display and the display of the program being de-
                bugged. This is not done by intuition or the like, but
                by PURE HARDWARE. For this reason, COP needs to know the
                address of the copper list of this program, and with the
                ECS-chipset, the BEAMCON0 value. While both is available
                in the graphics library, you must set them by hand if
                execbase is destroyed or the program debugged uses the
                hardware register to setup its display.
                While COP can almost always establish its screen, it is
                sometimes impossible to restore the programs screen
                completely - some hardware registers are write-only.
                In this case, you MUST use remote-debugging.
                If foreground or background mode has been active (see
                below) they are deactivated by the IOCD command.

                IOCD.S                  (does not take arguments)
                Toggle between build-in terminal and remote-debugging.
                If you switch to an external terminal, you should make clear
                that this terminal is online, or you might fail to enter
                a second IOCD.S to switch back to the build-in one.
                Everytime the terminal is changed, COP retries to get the
                terminals type to setup type-3 or type-4 communication.
                For more information about COP's internal terminal format
                and auto-identification read the "Terminal.doc" file
                included in this drawer.

                IOCD.C                  <expr>
                Set the address of the copper list of the user-program to
                re-establish the user's display. If <expr> is omitted,
                the "here" pointer is used. You won't need this command if
                you debug programs that use the "standard" graphic system,
                since COP extracs the address out of gfxbase itself. But
                if the user's program uses the hardware registers directly,
                COP does not recognize this change of the copper list.
                In this case, search with the FIND command for a write to
                the hardware register and set this value as user-copperlist
                with IOCD.C <expr>. It is seldom easy to find it, so
                good luck...
                If you have problems with programs using custom copper
                lists, you should try the interrupt driven display using
                the IOCD.I command (then you get trouble with
                interrupts instead of copper lists... ;-)

                IOCD.I                  (does not take arguments)
                Toggle between copper list driven display and interrupt
                driven display.
                The standard way for COP to display information is to
                setup a copper list and to load it into the hardware. Later
                on, if the program is started again, the system copperlist,
                which can be set by IOCD.C, will be loaded back.
                This will, of course, cause trouble if the program changes
                the copper list on its own.
                The best solution is of course to change to remote de-
                bugging using IOCD.S, but startig with release 1.30 COP
                can be forced to use a different method of display.
                The interrupt driven display does NOT use copper-lists,
                but uses the vertical blank interrupt to write the
                hardware registers. COP tries its best to keep the program
                setting valid, e.g. if the program disables the interrupt,
                COP excludes the user VBI from running. However, this is
                really a bit tricky and may fail. A second drawback is
                that the display produced by interrupts is much simpler
                and does, for example, not support line highlighting.

                IOCD.B                  (does not take arguments)
                Set COP to background mode, i.e. COP's display is never
                setup and the users display is kept active. However,
                you are still ready to enter commands. This mode is
                somewhat impracticable since you don't see what you type.

                IOCD.F                  (does not take arguments)
                Set COP to background mode, i.e. COP's display is not
                removed from the monitor (only execption: a GOPG command
                or the G subcommand of the STEP-command). Use this command
                to avoid the flicker that occurs if the screen changes.
                There's one caveat with this command and the STEP-command:
                Since the displays are not swapped, the user program may
                destroy COP's display by writing to a hardware register or
                may get unexepected results reading a register while COP's
                display is active.
                So watch out and disable the foreground mode if you want
                to step this type of commands.

                IOCD.R                  (does not take arguments)
                Disables foreground and background mode and restores
                normal display swapping.

                IOCD.Z                  <expr>
                Set the screen size of the build-in terminal to <expr>
                lines. If <expr> is omitted, the actual display size
                will be used.
                The standard screen size is 28 (=$1C, remember COP always
                thinks in HEXADECIMAL !) lines, but this might be too
                large for some monitors. To prevent you grabbling at your
                monitor, this command can be used to setup a fitting
                display size. However, the screensize is limited to 8 to
                28 lines and will always be centered.

                IOCD.L                  <expr>
                Setup the number of lines until COP presents its ***more***
                message to ask for continue. This number is more an
                approximate value as some outputs can't be broken up into
                lines (for example the register display does never generate
                a ***more*** message).
                If <expr> is not given, the command uses the last value.
                (Remember that COP thinks in HEX, so 10 is not TEN but
                SIXTEEN !)


                IOCD.M                  <expr>
                Set the value to be written to BEAMCON0 if user display
                should be rebuild. This command is not required unless
                an application uses the hardware registers directly.
                See IOCD.C and IOCD for more information about this
                feature.
                If possible, COP tries to build a NTSC-display because
                it is less flickering than a PAL screen. I think there
                should be no problems with this feature, even commodore's
                @#!?!-monitor supports 60Hz displays and most european
                TVs will do so, too. If there are problems, use the next
                option to use a PAL display instead, or use the PAL
                command line option (see below). Some flicker fixers
                might have problems with the long/short frame toggling
                of the NTSC display, COP offers the PAL60 option.


                IOCD.V            (does not take arguments)
                Toggles the display mode between NTSC, PAL and PAL60.
                ECS or better is required for this function.

                IOCD.P                  (does not take arguments)
                Toggles printer output.

                Not all commands cause a printer output, e.g. the edit
                and step commands do not, since they are interactive.


                IOCD.Q                  (does not take arguments)
                Toggles printer support via the build-in printer driver
                thru the parallel port of the amiga or the terminal
                connected to COP (this is the default).
                If you use the build-in terminal emulation, this command
                will make no difference at all, but with an external type-5
                terminal COP will either print itself or tell the external
                terminal to start or stop printing. The later method is of
                course the better one, it does not take over the parallel
                port hardware.

                All IO-commands but the L,S,P and Q subcommand don't make
                sense in a remote-debug session and don't do anything in
                this case.

                IOCD.E            (does not take arguments)

                This command does not take any arguments. It will send a
                FORM FEED control character to the connected printer, to
                eject the paper. This might be needed by some laser or
                deskjet printers.


ENVI            V                       R,L,I,B,X,E,M,F,D,C,U,O  <expr>
                Enviroment settings, mode settings and so on.

                without extension       Not valid. This command MUST
                be extended.

                ENVI.R                  (does not take arguments)
                Enter raw mode. In this mode,
                execbase is not used at all. There are much consequences
                of entering the raw mode: The display copper list and
                beamcon0 must be set by hand (with IOCD.C and IOCD.M),
                interrupts are disabled if COP is entered, all list
                commands depending on exec-lists, all task commands and
                all capture commands refuse to work. The EXIT command
                is not available, too. The SegTracker interface will be
                disabled, too.
                There is no message if these commands are still entered.

                All exceptions except interrupts cause now COP to inter-
                cept, even if there is an exception handler installed in
                the active task - normally it's no problem to run COP
                parallel to a "normal" debugger, but in RAW-mode COP will
                capture even its breakpoints.

                If you've entered the raw mode once, there's NO WAY
                TO SWITCH IT OFF LATER except a power up or a reboot,
                so be careful !

                You should use the raw mode if you MUST debug a program
                that uses the hardware directly. In most cases, it is
                necessary to use remote debugging, too.

                If you must use the chip-mem buffer, you are REQUESTED TO
                USE the raw mode too, or you will run into BIG TROUBLE
                with task switching activity.



                ENVI.L                  <expr> <expr>
                Add memory section. Cause COP does not use the exec
                memory list, COP tries to find the memory portions
                in your system on startup, i.e. chip mem, fast mem
                and the kickstart ROM. However, COP cannot handle
                "too complicate" memory models, e.g. fast mem that
                is split in several blocks or memory that is not
                aligned to 64K borders.
                To fit your needs, you may add a memory chunk of
                your choice to COP's list.
                The first argument specifies the start address of
                the block, the second the (exclusive) end address,
                if both are equal, this memory block will be removed
                from COP's private list.

                This memory list is used for the FIND and FILL commands,
                memory is scanned for all addresses in it.

                NOTE:           Normally, the memory in an Amiga is
                typically not organized in a linear way, some memory parts
                are mirrored to others and the memory is possibly split
                into some chunks, e.g. if you have a memory expansion
                card in an old Amiga 2000B with ranger-memory (slowmem).
                In this case, your fast mem will fill the addresses
                0x00020000 to ??? and 0x000c8000 to 0x000d0000. In this
                case COP will search the total area from 0x00020000 to
                0x00d00000, including some hardware registers in between.
                In this release, COP can not handle such complicated memory
                models, maybe later...
                (This is even better than pre-1.17 releases, which were un-
                able to work with A4000 memory models at all....)

                ENVI.I                  (no arguments)
                Disable the checking of changes of IRQ-vectors.
                Under normal conditions, COP checks the consistency of
                the MC68000 autovector table, used by COP to allow trace and
                breakpoint commands. If one of the entries are changed,
                you will be prompted by a message if it's O.K. to undo the
                change, to accept it (in this case COP writes the change
                back to its second vector table, which can be used by
                ENVI.F), or to ignore one or all changes.

                This change could be done by a faulty program, or
                by a program that wants to regain control over the whole
                system. In the first case it's better to answer U(ndo), in
                the later C(hange). If you use a MC68000, the address in the
                trace and illegal trap vectors are vital, and any change
                of them will prevent COP from being able to step thru
                programs. Also, COP needs at least one interrupt that
                occurs "often enough" to check the status of the break key.
                With a MC68010 or higher things are not that worse, cause
                COP uses the VBR register to move the autovector table
                to a different part of the memory. However, changes to
                the old table will be respected, although COP does not yet
                notice the change of the VBR register. In case you notice
                that the VBR has been changed, set it back to the old
                value which can be found in the label COPVBR and place the
                new value in the virtual vector base called VVBR.

                If you disable the IRQ-checking, all changes to the
                autovector table are ignored.

                ENVI.C                  (no arguments)
                Enables the IRQ copy back mode.
                Instead of watching the low-memory vector base, COP keeps
                an eye on its own vector offset and copies the changed
                vectors on request to the virtual vector base. This option
                should be choosen if you want to debug a program that
                directly writes to the vector base, like ShapeShifter.
                The command line option "MacMode" enables this automatically.
                Be warned: Enabling the copy back mode disables the check
                for the low memory vector table, which is normally used by
                the Amiga OS.
                This check can be disabled with the ENVI.I switch described
                above and works of course only for the MC68010 or better.


                ENVI.B                  (no arguments)
                Toggles the ChipMem backsave buffer.
                The display build up by COP's internal terminal emulation
                needs some chip memory that might be occupied by the
                program you want to debug. If you want to prevent COP
                from overwriting this area, you must:
                o) provide a backsave area using the BUFFER keyword on
                   the command line when COP is installed
                   (usually in the startup-sequence)
                o) enter the ENVI.B command to enable this buffer
                o) you SHOULD use the Raw-mode to prevent conflicts with
                   multitasking

                If the buffer is enabled, COP will backup the occupied
                memory area each time it builds its own display and will
                restore it, if the program's display is restored later.
                However, this backup mechanism is not (yet) fully trans-
                parent to other parts of COP, but the UNAS and DUMP
                commands keep care. It will be therefore convienent to
                place COP's CHIP hunk an uninteressting part of memory,
                e.g. the display buffer of the debugged program would be
                fine. To prevent problems with the blitter, COP will wait
                for the blitter to complete before swapping the memory.
                In all other cases the blitter will be just stopped.

                ENVI.X                  (no arguments)
                Affects the way the disassembler handles the indexed
                indirect mode with label generation. The default is, that
                the address which is used for label generation is given
                by the base register plus the index. This is most com-
                fortable if, for example, all entries of an indexed table
                have labels associated to them. If, however, you want to
                reassemble a part of code, this would be fatal since
                all assemblers calculate the displacement, which will
                be replaced by the label, as a distance to the base
                register without the index. So if you switch out the
                index inclusion, you will only see labels associated
                to the base of a indexed table.

                ENVI.E                  (no arguments)
                Toggle the label generation on or off. If you do not want
                to see labels, for example in a search process looking for
                a instruction with specific address, you can switch out
                the label generation at all using ENVI.E

                ENVI.M                  (no argument)
                Toggle the build-in memory manager. This part of code
                in COP protects you from writing into hardware and non-
                existing memory, as well as it does the memory re-
                mapping for the chipmem-buffer. If, for special purposes,
                you want to disable this feature, use ENVI.M

                ENVI.F                  (no argument)
                Toggle the place where the exception vectors are stored.
                The default location is at address 0, but since this is
                chip memory, exception handling gets slow. If you use
                ENVI.F, the vector base will be located in the fast-memory.

                Warning! ENVI.F does NOT change the vector base register
                at all, since it is pointing to COP's own vector base at
                any time. Instead, it says COP where to look for the system
                vectors, so it changes only the virtual vector base VVBR.
                Warning ! ENVI.F will overwrite the virtual vector base
                register VVBR of COP in order to work ! So do not use this
                command if you setup your own VVBR.

                This command only takes effect if running under a MC68010
                or better, since the plain MC68000 does not have a VBR.


                ENVI.D                  (no argument)
                Toggle the default input radix, with is set up as hex,
                to decimal and back.

                ENVI.U            (no argument)
                Toggle the MMU bypass. All COP memory accesses usually by-
                pass the MMU of the 68020 or higher processors, so you see
                the true physical addresses. This can be disasterous if COP
                is used on an A3000 because disabling the MMU disables the
                image of the OS, too. Use ENVI.U to tell COP not to touch
                the MMU. That will have, however, certain consequences:
                First, all addresses shown in COP will be logical addresses,
                not the pure physical addresses. Reading or writing
                non-existant or pure system addresses with MuForce
                enabled will cause COP to crash by a bus error (that's harm-
                less for COP, but you won't be able to alter these addresses
                at all).
                The command line option NOMMU can be used to enable this
                option by default. In any case, be careful with it.

                ENVI.O            (no argument)
                This is a 060/040 specific setting. It selects whether COP
                should bypass the non-implemented instruction exceptions
                to the 68060/68040 library or capture them itself.
                The command line option NOEMU does quite the same, namely
                enabling the bypass.

                It is, however, not yet clear if this option works or makes
                any difference at all. *sigh*


SPLT            /               C               <expr>
                This command is available ONLY if you use the build-in
                terminal or an external type-3 or type-4 terminal. It
                won't work with a raw ASCII-terminal.

                COP has the ability to split off a part of the screen for
                displaying some information permantly. This information
                in then updated each time you enter a command or COP
                looses or regains control over the system. For example,
                splitting the screen and displaying the register set in
                the upper part of the screen while tracing is highly use-
                ful and is nowadays standard for all debuggers.
                Cause COP is "a little" different from "the common
                debugger", you must enable this feature by hand, and due
                to the raw display system, it's not available in general -
                a raw ASCII terminal can't split the screen.

                without extension       COP displays a new prompt and you
                should enter a command that shall be executed each time
                the display must be updated. The output of this command is
                then displayed in a separated part of the display.
                It is possible to execute more than one command if you
                separate the commands by colons.
                The argument following the SPLT-command determinates the
                approximate size of the split-off part of the display
                (in lines; remember that all numerical values are HEX-
                VALUES by default !). If there's not enough room, not
                all commands will be executed.

                There are a few caveats to remember when using the SPLT-
                command:
                -Not all commands are splitable, e.g. the SPLT and the
                STEP commands (since that doesn't make sense at all...)
                -Some commands are splitable, but it's not very useful
                to split them, cause they get executed each time the
                display is updated, e.g. the GOPG and the EXIT commands.
                -Almost all commands change the "here"-pointer. This is
                NOT true for commands executed in the split-window, i.e.
                they can READ "here", but do not change them.
                This is somewhat useful since, while tracing, the "here"
                pointer contains the address of the first command of the
                lower window, e.g. splitting the command "d.w" will dump
                the obcodes of the program in hex.

                Some useful commands for splitting:
                REGS            will present a auto-updating register dump
                NODE .a6        will print the name of the library pointed
                                to by a6
                DUMP.L .a0      will dump the memory pointed to by a0.
                                (display will change if a0 changes, of
                                course)

                (Remeber that you should supply a dot in front of the
                register names to distinguish between registers and
                addresses)


                Remember that you can execute more than one command once,
                e.g. REGS:NODE .a6


                Another idea about splitting is to use it when searching.
                COP halts now searching as soon as something is found and
                refreshes the split-off command, with the "here" pointer
                set to the found command. Thus, splitting the screen with
                a command like "u >-8" will disassemble the region around
                the found byte everytime the search succeeds.


                SPLT.C                  (no arguments accepted)
                Remove the split window and return to normal operation.


                NOTE:
                This command is always executed if a part of COP causes
                a crash. Mainly because this part could be the split-off
                command, creating an infinite loop of crashes when re-
                freshing the screen after the crash-message.

SKTB            T               <expr>
                Stack traceback.

                Search the stack at the given address or at the address
                given by the active stack pointer for data- and
                code addresses. This will be useful if you want to find
                out which part of code called a faulty procedure.

                COP TRIES to find out if the data on the stack is
                just garbage (which won't be printed) or a pointer
                to data, or a return address to a piece of code.

                In the later case, it tries to find a label near that
                code address, to provide you with the name of the calling
                routine.

LABS            A            E,S,B,G,T,V,A,U,L,F    [name]
                Dump labels.

                This command prints informations about label definitions
                loaded into COP. A line dumped by this command will look
                like the following:

label name    :    value    (+ base)        (flags)

                Some labels are either relative to a base, which is printed
                in hex if so, or relative to an exec node. It's name is
                printed in this case.

                The characters in the brackets specify the type of the
                label:

                A    absolute address
                E    equate. An easy to remember expression representing
                    a number.
                N    an address relative to a node, thus, an offset.
                V    a function vector of a library or a device.
                R    an offset relative to an absolute base.
                S    a size of something. Currently not supported.
                B    a bit definition.
                L    A lineA trap definition (not required by the
                    Amiga-OS, but by the Mac OS)

                s    A COP internal (system) label. There are currently
                    only four system labels.
                r    A read-only label.
                k    A resident label, can't be removed with FLUSHALL
                t    A temporary (so, user) label. Can be removed with
                    FLUSH.


                The "name" argument specifies the label you'd like to know
                information about. Wildcars are welcome here, COP knows
                only two wildcards, '?' for one unknown character and '*'
                for a sequence of unknown characters. If you don't give a
                name, COP selects "*" for you as default, i.e. will show
                all label.

                The extensions specify the type of labels in the list:


                LABS.E            [name]
                Dump equates only.

                LABS.S            [name]
                Dump only sizes.

                LABS.B            [name]
                Dump bit definitions.

                LABS.G            [name]
                Dump gurus.

                LABS.T            [name]
                Dump line-A traps.

                LABS.V            [name]
                Print function vectors.

                LABS.A            [name]
                Print addresses. Absolute, relative or node relative.

                LABS.U            [name]
                Print all user defined (temporary) definitions.

                LABS.L            [name]
                Print all definitions.

                LABS            [name]
                Print all user defined addresses.

                LABS.F            <expr>
                Find the label nearest to and behind the given address.
                This is useful if you know only the absolute address in
                memory and want to relate it to the name of a subroutine
                of your program.

SEGM            Q            <expr>
                Find segment offsets.

                This command takes a memory address and tries to find out
                the program this memory belongs to. If successful, COP will
                print the segment (=hunk) number of that program, and the
                offset within that hunk the given address belongs to.

                Michael Sinz' "SegTracker" must be active for this service!



XI) COP arguments to the command line and ToolTypes for the Workbench
---------------------------------------------------------------------

Here a list of arguments COP acceptes as arguments when getting started
from the shell. However, it's possible to start COP from the workbench
and to supply the same arguments as tooltypes. Simply create a tooltype
of the same name for each keyword.


KEYMAP  <keymap>        Set the keymap COP should use for the build-in
terminal. Please note that you CAN NOT change this keymap with the
SetMap or SetKeyboard command. This keymap is of course not used for
remote debugging.
The keymap file is searched in the DEVS:keymaps drawer (not in KEYMAPS:
cause this logical device is not standard with Kickstart 1.2 or 1.3)
or in the keymap.resource. You need to supply AT LEAST AT STARTUP
a KEYMAP argument to define the keymap COP shall use. (There's no default
in this release, a missing keymap argument will result in an unusable
build-in terminal)


SERIAL                  Choose remote debugging
DISPLAY                 Choose build-in terminal for debugging
Note that you MUST supply the DISPLAY argument if you want to enter COP
by a shell command or COP will switch to remote-debugging.


LINES <number>          Set the number of lines of the build-in terminal
screen, the default is 28. This argument will be ignored if COP is already
loaded, use the IOCD.Z command instead.

BREAKKEY <number>       Set the keycode (NOT the ASCII-value !) of the
                        BREAK-key. This value will be used only by the
                        internal terminal emulation and will be ignored
                        under remote debugging.
                        Some useable keys (in other words: You
                        MAY use the return key, but...) are:

                        93      the asterisk on the numeric key pad
                        90      the braket-left key on the pad
                        91      the braket-right key nearby
                        74      the minus key on the pad
                        94      the plus key underwards
                        60      the dot on the key pat
                                this is the DEFAULT.

                        You may also use hex numbers if you place a $ or a
                        0x in front of them.

RESIDENT                Load COP resident into memory, i.e. COP will survive
a reset if execbase is still o.k. and need not to be reloaded. This option
is useful if you want to debug startup-code. If used together with
MuForce, you might want to give the "RESTOREVBR" keyword as well, see
below.

REMRESIDENT             Remove COP from the resident list and free all its
memory. Cause COP can not be removed completely, RESTART YOUR COMPUTER
IMMEDIATLY AFTER EXECUTING THIS COMMAND. Some code may write over COP's
still installed interrupt code resulting in a fireworks display or a crashed
harddisk (oh what a fun...).


GO                      Start a debug session using COP.

BUILDINPRT              Use the build-in printer support thru the parallel
port of the Amiga instead of the external terminal printer support. This
option works like the IOCD.Q command.

TERMINALPRT             The counterpart of BUILDINPRT: Use the printer pro-
vided by the terminal connected to COP. If you choose the build-in terminal
emulation, this won't make any difference. However, if you debug with an ex-
ternal terminal, the printing will be done thru its port and not thru the
amiga parallel port.


IRQDISPLAY              Select the buildin-terminal emulation, switch to
interrupt driven display. This acts like the IOCD.I command.

COPPERDISPLAY           Select the copper driven display as default.


IRQCOPYBACK             Select the IRQ copyback mode: COP does not watch the
low-memory interrupt vector table, but its own vector table and will copy
changes to the virtual vector base. This is the command-line counterpart of
the ENVI.C setting.

NOIRQCOPYBACK           The default operation of COP: Watch the standard
interrupt vector table, which is located at address 0 and up. Both checks
can be disabled with the ENVI.I switch.

RESTOREVBR              Instruct COP to re-install its own vector base
register. This keyword is needed if COP is made resident and used in con-
junction with "MuForce". Since "MuForce" installs its own vector base table
on top of COP, a resident copy of COP won't be able to capture enforcer hits
any more. Use this option to restore the VBR of COP, right after
installing MuForce.

MACMODE                 This macro switch enabled some options and settings
required for COP to run safely under the "ShapeShifter" Macintosh emulator.

SET60                   Tell COP that a MC68060 processor is in your system,
although exec.library does not know. The standard Amiga OS 3.1 does NOT
recognize a '60 processor, the correct flags are usually setup later by
a tool provided by the hardware manufacturer, mostly the 68060 library.
If you want to run COP prior to these tools, specify the SET60 option.
This flag DOES NOT change the processor flags in the exec.library!

NOMMU                   Disable the MMU bypass. COP won't touch the MMU and
keep it active all the time - as needed for amiga models that use the
MMU to load an OS image or to guarantee reliable DMA operations, as the
040 and 060 based Amigas. Disabling the MMU in this case will crash the
system because the OS will vanish. This keyword is identical to the ENVI.U
instruction.

MMU                     The default. COP bypasses the MMU for memory access,
all addresses will be physical addresses. This is somewhat dangerous if the
MMU is required for system operation, as for '060 and '040 systems or if
the MMU is used to map in a different version of the OS.

NOEMU                   Instruct COP to bypass the 060/040 emulator traps to
the 68060.library or 68040.library - which must be installed and running
at the time COP is launched. These exceptions are generated if the
68060 detects an instruction that is not supported by the CPU directly
but has to be emulated in software.

It is, however, not quite clear if this option makes any difference at all,
or if it works - simply because I don't own a '060 for testing.

EMU                     The opposide and default setting. COP captures all
emulator traps as software failures.

The next three options contol the video mode used by COP for its own display:

NTSC                    Use a NTSC screen for the debugger screen. This has
                        been the default for versions up to 1.56.

PAL                     Use a PAL screen instead. This is, however, more
                        flickering but required for some TVs.

PAL60                   This is a display mode half between PAL and NTSC.
                        It uses the base frequency of NTSC, 60Hz, but does
                        no long/short line toggling, like PAL. This mode
                        might be required to display 60 Hz with some oldish
                        flicker fixers.

PICASSO                 Tell COP that the "Picasso96" graphics system and
                        a graphics card is installed. COP will then try to
                        saveback the status of the RTG system and to bring
                        the native amiga display to front. This option
                        requires the "picasso96" installed, most important
                        the "rtg.library".
                        I don't know how well this works, though, it's
                        currently a bit "hackish".

NOPICASSO               Disable the use of the Picasso96 graphics software.

DARKEN                  Darken the native Amiga display upon initialization
                        of COP. This is useful for graphics board software
                        that leaves the native Amiga screen white.
                        This option is currently a bit "hackish".


Now some options that tell COP where to place itself in memory. They do
not work if COP is already loaded !

CODE where              Tell COP where to place its CODE segment. where
might be:
        FORWARD         Allocate memory from the beginning of the memory
                        area, so COP is placed at LOW addresses.
                        This is impractical in most cases.

        REVERSE         Allocate memory from the end of the memory, so
                        COP is placed at HIGH addresses. This was the
                        default up to release 1.18.

        address         Place COP at an absolute address, given in decimal
                        or in hex if preceded by $ or 0x.
                        This memory area must be available, as long as you
                        do not use the FORCE option.

DATA where              Tell COP where to place the DATA section. The
                        argument is the same as above.

BSS  where              ...same for BSS section

CHIP where              ...same for CHIP section. If you use an absolute
                        address here, make shure it is in chip mem !

LABEL where             ...same for LABEL section, which is needed if
                        you give a DDT (see below) and containes
                        the names and addresses of DDT labels.

BUFFER where            Tell COP to use a chip-memory backup buffer and
                        place it according to the argument. You MUST
                        provide this argument if you want a chipmem backup
                        area, or the ENVI.B command won't work.

RESIDENTSTRUCT where    Tell COP where to place the resident structure that
                        is needed for COP to keep resident over resets.
                        This argument is only useful if you use the
                        RESIDENT switch too.

FORCE                   Tell COP to use the specified memory, even if it is
                        occupied by another program. WARNING !
                        YOU SHOULD BE REALLY SURE WHAT YOU ARE DOING if
                        you MUST use this option ! Portions of code of
                        other programs might get overwritten by COP, causing
                        a fantastic crash !

FLUSH                   Flush labels loaded as symbols from a segment,
                        e.g. loaded by CLIDEBUG or WBDEBUG.
                        This is done automatically every time if you
                        specify CLIDEBUG or WBDEBUG.
                        However, the labels defined in the DDT file
                        are left alone.

FLUSHALL                Flush all labels, even those defined in a
                        DDT file. The system labels AbsExecBase, Version
                        COPVBR and COPVVBR survive.

CLIDEBUG                Debug a program using the Shell interface. If
                        you want to give arguments to the program to
                        debug, INCLUDE THE COMMAND AND ITS ARGUMENTS
                        in double qoutes. Since a colon and an asterisk
                        is interpreted by COP as the beginning of a
                        comment, you MUST enclose these characters
                        in an additional pair of single quotes.
                        To simplify this, you might use the DEBUG
                        script.
                        CLIDEBUG always flushes the labels.

WBDEBUG                 Debug a program thru the workbench interface.
                        If you want to support a second icon which is
                        simulated to be clicked with the main program's
                        enclose THE MAIN AND THE SECOND ARGUMENT IN
                        DOUBLE QUOTES. DO NOT ADD ANY .INFO TO THE
                        NAME, even if you load an icon of project type.
                        The responsible program will be found and be
                        loaded.
                        WBDEBUG always flushes the labels.

SYMBOL                  Add the symbols of the given binary file to
                        the label buffer. To do so, you MUST support
                        the base address of the segment using
                        SEGMENT or FIRSTHUNK.
                        Adding of additional labels might be necessary
                        if you debug an overlayed program. COP cannot
                        load all labels on startup, since it is not clear
                        where the overlay nodes will be placed in memory.
                        Remember the base address of the program if loaded;
                        Later on, if the overlay nodes are present, reload
                        the symbol table by FLUSH SYMBOL <progname>
                        FIRSTHUNK addr.

FIRSTHUNK               Give the APTR to the first byte of the first hunk
                        to which the labels to be loaded belong.
                        Either FIRSTHUNK or SEGMENT MUST BE USED as an
                        additional argument if you use SYMBOL.

SEGMENT                 Give the BPTR, as available from LoadSeg(),
                        of the segment to which the labels to be loaded
                        by SYMBOL belong.
                        Either this or FIRSTHUNK IS REQUIRED for SYMBOL.

CALC                    Calculate the expression given. Everything COP's
                        EVAL command can evaluate is valid here, even
                        defined labels. So to read the value of ExecBase
                        using the Shell is quite easy:
                        COP CALC [AbsExecBase]
                        Note that this allows using COP as a symbol data-
                        base, e.g. to remember the system entry points.

                        COP CALC OpenLibrary
                        will give the offset of the OpenLibrary system
                        call, provided you added it using a DDT.
                        The only caveat is that COP will assume all
                        numbers are in DECIMAL unless preceeded by $.
                        (Different to how expressions are handled usually!)
                        The $ notation, however, may conflict with
                        shell variables, so enclose the argument, also
                        if it contains spaces, in double quotes.


If you want to build an icon to start COP from the workbench, use for
example the following tooltypes:

DISPLAY                 MUST be present to prevent COP from remote-
                        debugging mode.
GO                      MUST be present if you want to start COP.



DDT file                Setup COP's labels using a data description
                        table. The syntax of this file is descripted
                        below, and a default table "startup.ddt" is
                        included in this drawer. If you want to run COP
                        together with the macintosh emulator, you should
                        specify the macintosh-version of the ddt file
                        called MAC.ddt and the MACMODE command line
                        switch.

                        You should use this option in your startup-
                        sequence to load all default labels.

                        It is fine to call COP again with this option
                        if you want to add some labels, however, if you want
                        to reload the table, you should flush all the
                        old labels with the FLUSHALL option.

PRE file                Provide or create a precompiled version of a DDT
                        file. If this argument is given, COP tries first to
                        read the label database from the "pre" file. If
                        this file is not available, COP will read the usual
                        DDT file and create a "PRE" file for you. The ad-
                        vantage of precompiling "DDT" files is that they
                        are parsed much faster. Their format is, however,
                        private.

Of course, if COP is already present, the code loaded will get started and
will not be loaded again (and therefore, some options are useless in this
case !)

If you want to debug a Shell program, this command line would be nice:

COP CLIDEBUG "c:copy s:Startup-Sequence to '*'"

will debug the copy command in copying the startup-sequence to the console.
Please note the necessary quotes around the command line and the star.


To debug a Workbench progam, say the Shell-Icon, type:

COP WBDEBUG "SYS:Shell"


Debugging overlayed programs is a bit tricky. First load the program
itself, e.g. with

COP CLIDEBUG "SetVNC"

Now write down the address of the breakpoint when COP is entered.
Step thru the code until a new overlay segment is loaded. To do so,
set a breakpoint in the overlay manager, which will always be the first
hunk of the program. Then, load the symbols of the overlay code using

COP FLUSH SYMBOL "SetVNC" FIRSTHUNK 0x<addr>

where addr is the address of the breakpoint you wrote down before.

One caveat using overlays is that the structure of the overlay table
depends on the overlay manager the program uses. There are quite a lot
of them, however, COP only knows the default one supplied with the
linker BLink or SLink. As an example, the overlay structure of
DPaint II or COP (yes, that's me...) is private and is not supported
by COP. In this case, you cannot load symbols which are placed in the
overlay nodes, sorry.


If you want to use COP with the shapeshifter macintosh emulator, I suggest
the following command line:

COP FASTVBR NOMMU MACMODE DDT S:Mac.ddt

plus your prefered keymap and display settings. COP can be entered from
the macintosh finder interface thru the hot key, as usual. Once entered,
the hardware traps are captured by COP, not by the MacOs. However, the
system failures (except those generated by hardware traps) are still left
to the Os. This might change in a future release.



XII) Syntax of a data description table
-----------------------------------------------------------------------------

The data description table contains information about labels, that are
litaral names given to addresses to make code more readable. COP intro-
duces a new concept of label creation not available with any other de-
bugger.
The labels are sorted by "type", as there are:

-       absolute labels, refering to one static address in memory.
        This is the only type of label most debuggers support.

-       equates. Those are simply names for numerical constants and
        are never used in actual disassembling. You may use it, how-
        ever, in expressions (and, in a release to come, in the
        microassembler)
        Typical equates are offsets of fields in structures.

-       node relative labels. If COP finds a specific base pointer
        points to a named exec-node structure (e.g. a library), this
        type of label is used to generate a name for the offset from
        the base of the node to the piece of memory which is addressed.
        A typical case is a entry point in a library, but also the full
        structure of a library can be addressed like that. So the default
        ddt includes the whole structure of execbase and gfxbase.
        Since the linking is done in the run time, it is not necessary
        to open these nodes, and the nodes even does not need to exist in
        memory while creating the labels.

-       address relative. This type is currently not used, but is
        useful if a base register is setup to point to the data region
        of a program. Typically, this will be a5 or a4.

-       a guru equate. This special type is used for giving readable
        names to guru meditations and is never used by the disassembler,
        but by the REGS.G instruction - And therefore every time COP is
        entered by a crash.

-       bit definitons. Useful for giving readable names to bits, but
        not used by the disassembler (there are way to many of them).

-       New with version 1.52 of COP, lineA-emulators can be named, too.
        These traps are never used by the AmigaOs, but function as Os-
        calls for a macintosh or Atari-ST emulator.

The syntax of a ddt file is a strange mixture of the syntax of the CBM
.fd-files and assembler include files, so you can use your .FD-files
and include files WITHOUT ANY CHANGE, provided you use the CBM macros
defined in exec/types.i and provided that you do not use forward
references, as they are not supported.

Entries in the DDT are
i)      COPDDT-commands, a superset of the commands in the .fd files.
        COPDDT-commands are preceeded by two hashmarks and MUST be placed
        in the very first column.
ii)     Pure labels and function entries are given by their names and must
        placed in the first column of the file, like labels in assembly
        language. As a special case, a label might be followed by a
        EQU or SET opcode. The first produces an equate label with
        a given value, and the second is ignored by COP since it is
        only used to keep track of the included files.
        If no value is given for a label, the contents is taken from
        the offset-counter which can be set by ##offset or ##bias.
        The type of the labels can be set by a COPDDT command pre-
        ceeding the label, except for labels defined by EQU, which
        are always equates.
        A pure label without EQU will always increment the ##offset
        counter by a size which can be set by ##increment.
iii)    Pseudoassembler commands which are named like the default CBM-
        macros in the exec/types.i file. They mostly define a label of
        a type defined by some COPDDT command above, and the value
        is also taken from the ##offset counter. However, the
        increment depends on the pseudoassembler command.
iv)     Comments are introduced by a colon or an asterisk like in
        assembly language.

Here the COPDDT-commands:
##node name             Setup the next labels as labels relative to the
                        node with the given name. Should be used for
                        library offsets.

##vectors name          Identical to ##node, except that it defines function
                        vectors. The label values should be negative.

##guru                  Setup the next labels as numbers of guru-meditations

##absolute              Setup the next labels as absolute addresses.
                        Never used with the Amiga-Os, since there is only
                        one fixed address (AbsExecBase), which is already
                        defined as a label. However, this type is used for
                        the low-memory variables of the macintosh Os
                        (what a horror !)
##relative <expr>       Setup the next labels as offsets to the address
                        given by <expr>, which need not to be a number,
                        and may contain other evaluable labels. However,
                        forward references are not supported.
##equate                Setup the next labels as pure equates.
##linea                 Setup the next labels as line-a traps, as used by
                        the MacOs and Atari ST. Useless for the Amiga.
##offset <expr>         Set the offset of the next labels relative to their
                        base. With amiga only useful for labels of ##node,
                        ##relative or ##equate type, since there is only
                        one fixed absolute address in the amiga and no
                        line-A emulators. Useful for ##absolute and ##linea
                        under MacOs and Atari ST.
##bias <expr>           Set the negative offset of the next labels. Will
                        be used by .fd files to set library entries and is
                        identical to ##offset except that the value of
                        <expr> is negated (sign-changed).
##increment <expr>      Sets the default incrementation value of the offset
                        counter. Should be set to -6 prior to including
                        .fd files, since each entry takes up 6 bytes, and
                        libraries grow to lower addresses. If you want to
                        define a table of LONGs, set the increment to 4.
                        This value is added to the ##offset counter every
                        time a pure label without a size gets defined.
                        Function entries in a .fd file are "pure labels"
                        in the sense of COPDDT.
##base name             Define the name of a library base. Used by the
                        .fd files. Will define a label of offset
                        zero.
##include name          Include another file in the ddt. There is NO
                        check for cyclic dependence, so WATCH OUT !
                        If the name contains spaces, include it in double
                        quotes.
##end                   End an ddt file. Also used by .fd files.

##private               Quietly ignored by COP, only used in fd-files
##public                Also ignored.

Empty lines or lines starting with a colon or a star are read as comment-
lines and are ignored, too.

Label definitions:
A "pure" label is defined by giving only its name starting in the
first row of a line, like this:

##absolute 8            ; Labels are of absolute type
##increment 1           ; Set the increment of pure labels
mylabel                 ; comments are welcome ! This label gets the value 8
nextlabel               ; and this one 9, since the increment is 1

The value of the label to be defined is contained in the offset counter,
and it will be incremented by the value in ##increment every time.

Since fd-files contain functions and arguments, a (pure) label name is
cut in the first occurance of a left bracket:

myFunc(foo)(a0)         ;this label gets called "myFunc" and got the value 10

Labels can be set to given values using the EQU pseudoassembler directive.
These "unpure" labels neither need the offset counter nor increment it.
All labels generated by this syntax are of equate type, regardless of the
previous COPDDT command.
TRUE            EQU     1       ; an equate. Can be evaluated, but is
                                ; not used by the disassembler
                                ; the offset counter is untouched, too


The set directive of assembly language is known, but will be ignored without
any checking:
ARGC            SET     §       ;in assembly language syntactically wrong,
                                ;but completely ignored by COP.

The same goes for lines between a MACRO and a ENDM directive, since
COP does not support macros (and I think never will..).


Pseudoassembler commands:

They are called "pseudoassembler commands" cause they define labels in
assembly style, rather than .fd style. All macros in exec/types.i are
"emulated". The type of labels generated by them depend on the pre-
ceding COPDDT command, like ##absolute will generate absolute labels.
The value of the labels is given, as above, by the offset counter. This
counter can be set with the ##offset COPDDT command or the STRUCTURE
directive, and will be incremented by a value determinated by the
directive, unlike pure labels, which cause the value of ##increment
to be added.

Pseudoassembler directives MUST NOT start at the beginning of a line, but
MUST be preceded by spaces or TAB characters, like in assembly language.

Known directives are:

        STRUCTURE name,<expr>
Define a new label of given name as the base of a structure. The offset
counter will be initialized by <expr>, that is, the structure containes
unnamed field in the beginning of the size given by offset. The value
of the label defined will be zero relatively to a base, which can be
setup by ##node or ##relative. Defining an absolute structure does not
make much sense in this system.

        STRUCT name,<expr>
Define a substructure in a structure, that is, generate a label of given
name with the value as the value of the offset counter, and of type
given by a preceding COPDDT command. The offset counter is incremented by
the value of <expr> afterwards.

        LABEL name
Define a label with the value of the offset counter, which is not
incremented at all.

        UBYTE name[,<expr>]
Define one single byte, or array of bytes by generating a label. Its
value is given by the offset counter, and its type is given by a preceding
COPDDT command. The offsetcounter is incremented by 1, if the expression
is ommited, or 1x<expr> to generate an array.

        BYTE name[,<expr>]
Same as byte.

        UWORD name[,<expr>]
Define one single word, or array of words. Works like BYTE, but the offset
counter is incremented by 2 or 2x<expr>. If the offset counter is odd, it
is rounded to the next even number.

        WORD name[,<expr>]
Same.

        BOOL name[,<expr>]
Same.

        ULONG name[,<expr>]
Defines one long word, or array of longwords. Increments by 4 or 4x<expr>
and alignes offset counter.

        LONG name[,<expr>]
Same.

        APTR name[,<expr>]
Same.

        CPTR name[,<expr>]
Same.

        FPTR name[,<expr>]
Same.

        FLOAT name[,<expr>]
Same.

        DOUBLE name[,<expr>]
Defines a IEEE-double precision entry or array. Increments the offset counter
by 8 or 8x<expr> and alignes it.

        UQUAT name[,<expr>]
Same.

        QUAT name[,<expr>]
Same.

        EXTENDED name[,<expr>]
Introduced in COP, defines MC68881 extended precision entry or array.
Increments the offset by 12 or 12x<expr> and aligns it.

        ALIGNWORD
Explicitly aligns the offset counter to the next word.

        ALIGNLONG
Align the offset counter to the next long word.

        ENUM [<expr>]
Initializes the ENUM-counter by the given value. Does not generate any label.

        ENUMITEM name
Generate a label of equate type. The value is given by the equate counter,
which will be incremented by one after the definition.

        BITDEF pre,post,<expr>
Generate two (!) labels. The first is of bit-type and will be named
"preB_post" and will have the value given by <expr>. The second will be
named "preF_post", is of equate type and has the value of 1 << <expr>.

        IFD,IFND,ENDC
Ignored by COP

        INCLUDE
Ignored by COP. To include something, use the COPDDT command ##include.
This was mainly done to avoid unnecessary includes and to give the
control what will be included to the main DDT-file.

        LIBINIT
        LIBDEF
Also ignored by COP

        MACRO
        ...
        ENDM
Lines between MACRO and ENDM are ignored by COP, since it does not support
macros.


As noted above, the set of supported commands was choosen in a way such
that all orignal CBM-includes and .fd files can be used without a change.
Support of other style assembly include files (like DevPac's rs-counter)
are not supported and never will.
It is, however, sometimes necessary to explicitly define labels on one's
own. This happens mostly if the orginal include file defines useful
constants that should be relative to a base as equates. An example is
the definition of DOSBase in dos/dosextens.i. Since you cannot make
all labels relative to DOSBase, one must take this definition out
of the file.
Defining DOSBase as equates and not as node relative is of course not
illegal in COP, but will be of no use for the disassembler since it
ignores equates (there are too many of them to be of any use). This was,
as a second example, necessary in defining the hardware offsets.
Originally given as equates, they are now relative to the base of
the custom chip set. See the included example ddt file.

XIII) Precompiled files
-----------------------------------------------------------------------------

The 1.60 version of COP introduces the option to "precompile" DDT files for
faster startup. If you give a name of a pre-file on the command line with
"PRE filename", additional to the "DDT" keyword, COP will try first to load
all labels from this pre-compiled header. If successfully, the DDT keyword
will be ignored. If the "PRE" file is not available, COP will parse the "DDT"
file as usual and will create this "PRE" file afterwards so it is available
for later use.

The main advantage of precompiled "DDT" files is that they are way faster to
load, no parsing and no syntax check is required. The data format is
completely internal, please do not touch these files - they are purely for
COPs use and maintained completely by COP itself.

One caveat of "PRE" files is that they aren't updated automatically if you
change the original "DDT" file and there can be ONE and ONLY one "PRE" file
for the complete set of macros. Writing a partial set of label definitions
in a pre-file isn't possible. Either all or nothing!

The consequence is that you:

- should delete the "PRE" file manually if you made changes to the source DDT
file. COP will then re-create the "PRE" file the next time it is required.

- should only precompile the first DDT file that is loaded, that is the
"startup.ddt" file. Since this is the only DDT file in most applications,
that's not a restriction. DO NOT TRY to write PRE files for DDT files you
include afterwards - as they will not only contain the label definition in
the additional DDT file but in ALL DDT files. Loading these labels later on
might confuse COP.

As a rule of thumb: Only the Startup.DDT file should be precompiled.


XIV) Shell scripts
-----------------------------------------------------------------------------

Three shell scripts are provided with COP, to simplify work:

-Debug          Accepts a program name (full path required) and its
                arguments to be debugged by COP. Will load the program
                as if started from the Shell and set a breakpoint at the
                first hunk.

-WBDebug        Accept a workbench program and, optionally, a secondary
                selection, without .info. Starts the program and supplies
                the arguments thru a WBStartup message, as if started from
                the workbench.

-Calc           Evaluates the supplied argument. Labels are welcome, and
                the radix defaults to decimal. However, problems may
                arise if you use hex numbers cause the $ can cause
                conflicts with defined shell variables. In this case,
                enclose the argument in double quotes.


XV) COP and MuForce/Enforcer/Cyberguard
-----------------------------------------------------------------------------

COP 1.56 and up supports the Enforcer program if run on a MC68020 or MC68030,
it supports MuForce on any processor. It *might* support the Cyberguard, too,
but the 040 exception handler of this program is faulty and I won't recommend
this program for that reason.

There are two ways to run these tools together with COP, depending on which
output you need.

Method I):    Start MuForce first, then run COP.
Don't remove it later. This is the recommended way.

This will redirect Enforcer hints directly to COP. Faulty programs will cause
a bus error exception, and you're now able to debug these programs directly.
The enforcer won't cause any ouput, running "Sushi" is not necessary.

If you made COP resident, the COP invokation line in the startup-sequence
should contain the "RESTOREVBR" keyword, too. This is needed because the
order of installation will be different once COP is resident - MuForce
will now install on top of the resident copy of COP, hence, messing COP's
vector base register. This option will re-direct the vector base to COPs
interal base.

Do NOT use the CAPTURESUPER option of MuForce, and add the NOGURUPATCH
option. This will keep MuForce out from vectors required by COP.


Method II):    Start COP first, then load MuForce. It is possible to
remove MuForce later on, however.

The MuForce will work as usual with this setting, COP won't interfere in this
case.

However, as soon as COP is entered, it will complain about its vector base
being messed up by MuForce. You might want to simply ignore this warning.


MuForce and the FASTVBR option.
--------------------------------

That's a story of its own. If you want to run COP before MuForce, the
FASTVBR option IS REQUIRED. This is simply due to the fact that otherwise
COP will locate the virtual vector base in the first 1K/4K of memory as
usual - and this memory isn't available with MuForce.
Quite the same goes for keeping COP resident - it's in this case already
present when MuForce gets loaded, so FASTVBR is mandatory, too.

There's actually little reason NOT to use the FastVBR option except to keep
some badly written programs - mostly games - working.




XVI) COP and the 68060 / 68040
-----------------------------------------------------------------------------

The 1.61 release of COP should be able to support the 68060 processor -
however, as most of the support code is untested, it is not quite clear if
everything works as expected.


The following rules apply to COP and the 68060:
-----------------------------------------------

- Add the SET60 keyword to the command line option. That tells COP explicitly
  that it has to deal with the '060 processor. The execbase "AttFlags" flags
  field does not necessarely monitor the '060 processor correctly.

- Add the NOMMU keyword. The MMU operation is vital for '060 and '040 based
  systems, to mask certain regions of memory as "non-cacheable" as needed for
  DMA transfer and other reasons.

- Add the NOEMU keyword. COP will try to bypass the emulator traps to the
  68060 library. It is, however, not quite clear if this works as expected.

- Load the 68060 library BEFORE COP is run. This is usually done by the
  68060.library that gets loaded by SetPatch.

- Start COP after CyberGuard or Enforcer. This is the recommended way, but
  it is not yet quite clear if this works like it should. COP has to emu-
  late the access to the AbsExecBase location at address four, and this
  emulator code is quite tricky for the 68060. Even though I tried my best
  to test it with my 68030, it is not clear whether it works like it should.

- Add the FASTVBR option if you want to run COP before Enforcer/CyberGuard,
  or if you want to keep COP resident. Do not specify it otherwise.


COP and the 68040
-----------------

- Add the NOMMU keyword. It is required for proper DMA operation of '040
systems.

- Add the NOEMU keyword. COP will try to bypass the emulator traps to the
  68040.library.

- Run COP after MuForce. Don't use the Enforcer because its design is too
  static to allow proper operation. Don't use CyberGuard because its
  exception handler is not working properly.

- Run COP after loading the 68040.library. This is usually done by the
  SetPatch command anyways.

- Specify the FASTVBR keyword if you run COP before Enforcer, or if you
  want to keep it resident. Do not specify it otherwise.


XVII) Plans
-----------------------------------------------------------------------------

- Making the chip-buffer more transparent
- Better memory chunk support
- better disassembler, parts are already working
- a microassembler (in preparation)
- wildcards in node matching
- bitdefs should really be relative to something, but system includes
  do not give the information
- more macintosh support, thru a mac INIT.
- a MMU table lister ?

In the next time, there won't be...

- a floppy or harddisk support. There are so many filing systems and device
  drivers and I think using the 20K or more needed to implement this stuff
  can be used a better way.


XVIII) Final remarks
-----------------------------------------------------------------------------

COP should not be crunched or compacted since COP uses an internal overlay
format to load the debugger code if needed. To enter COP later with a
COP DISPLAY GO or equiv. the startup segment is loaded to memory only.

I wrote COP six years ago (1993) to find the reason of many crashes that
occured in my system. I found that most debuggers I knew were not
able to debug a system with execbase out of order or input.device crashed.
The first debugger I used to accomplish this task was the ROMWack, a very
simple, but nevertheless useful one.
It took a year to complete the first release of COP, so I can appreciate a
programmer's work and you should do so, too. Please use COP to find bugs
in your own code only, whenever every other debugger fails, e.g.
interrupt code or reset resident code. Use COP to find the reason of
system crashes that crash normal debuggers, but PLEASE DO NOT USE COP TO
FUMBLE IN FOREIGN CODE, since this will prevent people from writing
good programs. Not everthing is public domain today, support the good work
and buy software.

This program is decidated to all the bubbling idiots that debug own code
up to 4 a.m. in the morning ("It MUST work...").


P.S.: The reason for the crashes, if anybody cares, is the broken expansion
port in my A2000. Replacement motherboards are no longer accepted, because
I got a replacement now... (-;


Thank goes to:
-Oliver Spaniol for letting me debug this proggy on his '060.
-Mark Watson for his help with the '060 code.
-Werner Müller for providing a 040 and a (working) 6.2 motherboard for
 a bargain.



If you like this program, if you have any suggestions, if you want to get a
newer release of COP, write to:


Thomas Richter
Rühmkorffstraße 10 A

D-12209 Berlin

Germany
-------

or send electronic mail to

[e-mail]


There's also a web site you should try:

WWW:    http://www.math.tu-berlin.de/~thor/thor/index.html



It might be possible that COP does not work on YOUR Amiga, some parts of
the code are very tricky and hardware dependent. I tried to avoid such
problems, but one can never know. If COP fails on your computer, send
me a mail and descripe as best as possible your problems. However, debugging
by mail is a complicate task....


Thank you for reading and have a good time...

        THOR    (February 2001)